Overview

agentty is a terminal-first Agentic Development Environment (ADE), designed for building software alongside AI agents. This project is built using agentty itself, including the docs and docs-site you are reading.

It runs AI coding agents in dedicated AI sessions.

What Agentty Provides🔗

When you start a session, Agentty does the operational heavy lifting for workflow safety:

• Spawns a clean worktree branch for every session.
• Runs agent-driven edits in isolation from your base branch.
• Keeps terminal output, diffs, and generated changes in one reviewable stream.

Typical Flow🔗

1. Open a repository and start agentty.
2. Start a new session from the UI and ask for changes.
3. Let the agent modify files in its worktree.
4. Review the diff (d) and decide to apply or discard.

Worktree Isolation🔗

Every session runs in its own git worktree, created automatically when the session starts:

• The worktree branch is named agentty/<hash>, where <hash> is derived from the session ID.
• The branch is based on whichever branch was active when you launched agentty.
• All agent edits happen inside the worktree, keeping your base branch untouched until you explicitly merge.
• If worktree creation fails (e.g., git is not installed or permissions are insufficient), session creation fails atomically and displays an error.

Worktrees are stored under ~/.agentty/wt/ and are cleaned up automatically when you delete a session.

Key Concepts🔗

Next Steps🔗

• Installation — install Agentty and run it for the first time.
• Agents & Models — configure backends and choose models.
• Workflow — learn the interface layout and session lifecycle.
• Keybindings — learn the keyboard shortcuts for each view.